TypeSpec migration milestone 1: Generate Swagger from TypeSpec#4791
Open
kimorris27 wants to merge 24 commits intomasterfrom
Open
TypeSpec migration milestone 1: Generate Swagger from TypeSpec#4791kimorris27 wants to merge 24 commits intomasterfrom
kimorris27 wants to merge 24 commits intomasterfrom
Conversation
kimorris27
requested review from
alcasim,
bennerv,
cadenmarchese,
hawkowl,
hlipsig,
jharrington22,
kevinobriendotca,
mociarain,
mrWinston,
rogbas,
sankur-codes,
tiguelu,
tsatam,
tuxerrante,
ventifus,
wanghaoran1988 and
yjst2012
as code owners
Contributor
There was a problem hiding this comment.
Pull request overview
Migrates Swagger generation for the 2025-07-25 (and future) API versions from Go-struct-derived Swagger to TypeSpec-derived Swagger, relocating the new spec artifacts under api/ and adding tooling/docs to support the new pipeline.
Changes:
- Adds TypeSpec source-of-truth for
Microsoft.RedHatOpenShift/OpenShiftClustersand tooling to compile it to Swagger and generate examples. - Updates
make generateflow and introduces new targets/scripts for TypeSpec-based Swagger generation while keeping a legacy path for older API versions. - Moves/remodels API example files for
2025-07-25(removing legacy swagger examples and adding generated examples underapi/.../OpenShiftClusters/examples), and vendors common-types intoapi/common-types.
Reviewed changes
Copilot reviewed 79 out of 83 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| swagger/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/openshiftclusters/stable/2025-07-25/examples/PlatformWorkloadIdentityRoleSets_List.json | Removes legacy swagger example (moved to TypeSpec-generated examples under api/). |
| swagger/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/openshiftclusters/stable/2025-07-25/examples/PlatformWorkloadIdentityRoleSet_Get.json | Removes legacy swagger example (moved to api/). |
| swagger/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/openshiftclusters/stable/2025-07-25/examples/Operations_List.json | Removes legacy swagger example (moved to api/). |
| swagger/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/openshiftclusters/stable/2025-07-25/examples/OpenShiftVersions_List.json | Removes legacy swagger example (moved to api/). |
| swagger/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/openshiftclusters/stable/2025-07-25/examples/OpenShiftVersions_Get.json | Removes legacy swagger example (moved to api/). |
| swagger/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/openshiftclusters/stable/2025-07-25/examples/OpenShiftClusters_Update.json | Removes legacy swagger example (moved to api/). |
| swagger/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/openshiftclusters/stable/2025-07-25/examples/OpenShiftClusters_ListCredentials.json | Removes legacy swagger example (moved to api/). |
| swagger/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/openshiftclusters/stable/2025-07-25/examples/OpenShiftClusters_ListByResourceGroup.json | Removes legacy swagger example (moved to api/). |
| swagger/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/openshiftclusters/stable/2025-07-25/examples/OpenShiftClusters_ListAdminCredentials.json | Removes legacy swagger example (moved to api/). |
| swagger/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/openshiftclusters/stable/2025-07-25/examples/OpenShiftClusters_List.json | Removes legacy swagger example (moved to api/). |
| swagger/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/openshiftclusters/stable/2025-07-25/examples/OpenShiftClusters_Get.json | Removes legacy swagger example (moved to api/). |
| swagger/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/openshiftclusters/stable/2025-07-25/examples/OpenShiftClusters_Delete.json | Removes legacy swagger example (moved to api/). |
| swagger/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/openshiftclusters/stable/2025-07-25/examples/OpenShiftClusters_CreateOrUpdate.json | Removes legacy swagger example (moved to api/). |
| hack/swagger-legacy/swagger.go | Adds wrapper binary for legacy Go-struct-based swagger generation. |
| hack/ci-utils/isClean.sh | Updates cleanliness check to ignore TypeSpec-generated example churn under api/.../examples. |
| hack/apiclients/generate-swagger-checksum.sh | Removes old checksum helper (replaced by hack/api/generate-swagger-checksum.sh). |
| hack/api/swagger-from-typespec.sh | Adds TypeSpec formatting/compilation + example generation script. |
| hack/api/generate-swagger-checksum.sh | Adds checksum generation that can look in swagger vs api locations. |
| hack/api/build-dev-api-clients.sh | Adds client generation script (Go track1 + Python track2) for selected API versions. |
| docs/api-versions.md | Documents the new TypeSpec-based swagger generation workflow and legacy workflow. |
| docs/agent-guides/api-type-system.md | Updates “Swagger Generation” documentation to include the TypeSpec path and renames legacy generator references. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/tspconfig.yaml | Adds TypeSpec compiler/emitter config for Swagger emission + SDK emitters. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/suppressions.yaml | Adds TypeSpec migration suppressions for brownfield/legacy specs. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/readme.md | Adds AutoRest config for the new spec layout under api/. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/readme.go.md | Adds Go SDK generation guidance/config. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/readme.java.md | Adds Java SDK generation guidance/config. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/readme.python.md | Adds Python SDK generation guidance/config. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/readme.typescript.md | Adds TypeScript SDK generation guidance/config. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/models.tsp | Introduces TypeSpec models for the OpenShiftClusters RP API surface. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/main.tsp | Defines service namespace, versions, and top-level interface wiring for TypeSpec. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/client.tsp | Adds client-generator naming overrides for multi-language SDK compatibility. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/back-compatible.tsp | Adds legacy flattening and naming overrides for backward compatibility. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/OpenShiftCluster.tsp | TypeSpec resource + operations definition for OpenShiftClusters. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/OpenShiftVersion.tsp | TypeSpec resource + operations definition for OpenShiftVersions. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/PlatformWorkloadIdentityRoleSet.tsp | TypeSpec resource + operations definition for PlatformWorkloadIdentityRoleSets. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/PlatformWorkloadIdentityRoleSets_List_MaximumSet_Gen.json | Adds generated example under api/ for the new pipeline. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/PlatformWorkloadIdentityRoleSet_Get_MaximumSet_Gen.json | Adds generated example under api/ for the new pipeline. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/Operations_List_MinimumSet_Gen.json | Adds generated example under api/ for the new pipeline. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/Operations_List_MaximumSet_Gen.json | Adds generated example under api/ for the new pipeline. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/OpenShiftVersions_List_MaximumSet_Gen.json | Adds generated example under api/ for the new pipeline. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/OpenShiftVersions_Get_MaximumSet_Gen.json | Adds generated example under api/ for the new pipeline. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/OpenShiftClusters_Update_MaximumSet_Gen.json | Adds generated example under api/ for the new pipeline. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/OpenShiftClusters_List_MaximumSet_Gen.json | Adds generated example under api/ for the new pipeline. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/OpenShiftClusters_ListCredentials_MinimumSet_Gen.json | Adds generated example under api/ for the new pipeline. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/OpenShiftClusters_ListCredentials_MaximumSet_Gen.json | Adds generated example under api/ for the new pipeline. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/OpenShiftClusters_ListByResourceGroup_MaximumSet_Gen.json | Adds generated example under api/ for the new pipeline. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/OpenShiftClusters_ListAdminCredentials_MinimumSet_Gen.json | Adds generated example under api/ for the new pipeline. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/OpenShiftClusters_ListAdminCredentials_MaximumSet_Gen.json | Adds generated example under api/ for the new pipeline. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/OpenShiftClusters_Get_MaximumSet_Gen.json | Adds generated example under api/ for the new pipeline. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/OpenShiftClusters_Delete_MinimumSet_Gen.json | Adds generated example under api/ for the new pipeline. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/OpenShiftClusters_Delete_MaximumSet_Gen.json | Adds generated example under api/ for the new pipeline. |
| api/redhatopenshift/resource-manager/Microsoft.RedHatOpenShift/OpenShiftClusters/examples/2025-07-25/OpenShiftClusters_CreateOrUpdate_MaximumSet_Gen.json | Adds generated example under api/ for the new pipeline. |
| api/package.json | Adds Node/TypeSpec/oav dependencies and scripts for format/compile/examples. |
| api/common-types/rfcs/rfc7517.json | Vendors RFC common type definitions into api/common-types. |
| api/common-types/resource-management/v6/privatelinks.json | Vendors ARM common types v6 (private links). |
| api/common-types/resource-management/v6/managedidentity.json | Vendors ARM common types v6 (managed identity). |
| api/common-types/resource-management/v5/privatelinks.json | Vendors ARM common types v5. |
| api/common-types/resource-management/v5/networksecurityperimeter.json | Vendors ARM common types v5 (NSP). |
| api/common-types/resource-management/v5/mobo.json | Vendors ARM common types v5 (MOBO). |
| api/common-types/resource-management/v5/managedidentitywithdelegation.json | Vendors ARM common types v5 (delegation). |
| api/common-types/resource-management/v5/managedidentity.json | Vendors ARM common types v5 (managed identity). |
| api/common-types/resource-management/v5/customermanagedkeys.json | Vendors ARM common types v5 (CMK). |
| api/common-types/resource-management/v4/privatelinks.json | Vendors ARM common types v4. |
| api/common-types/resource-management/v4/managedidentitywithdelegation.json | Vendors ARM common types v4 (delegation). |
| api/common-types/resource-management/v4/managedidentity.json | Vendors ARM common types v4 (managed identity). |
| api/common-types/resource-management/v4/customermanagedkeys.json | Vendors ARM common types v4 (CMK). |
| api/common-types/resource-management/v3/privatelinks.json | Vendors ARM common types v3. |
| api/common-types/resource-management/v3/managedidentity.json | Vendors ARM common types v3 (managed identity). |
| api/common-types/resource-management/v2/privatelinks.json | Vendors ARM common types v2. |
| api/common-types/resource-management/v1/types.json | Vendors ARM common types v1 core types. |
| api/common-types/resource-management/v1/privatelinks.json | Vendors ARM common types v1 (private links). |
| api/common-types/data-plane/v1/types.json | Vendors data-plane common types. |
| Makefile | Introduces TypeSpec image/targets and updates generate + swagger checksum flow. |
| Dockerfile.typespec | Adds container image for TypeSpec toolchain execution. |
| .sha256sum | Updates spec checksum list to include the relocated 2025-07-25 swagger. |
| .gitignore | Ignores api/node_modules created by the new toolchain. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
kimorris27
force-pushed
the
kimorris27/ARO-23228-typespec-migration
branch
from
642b752 to
482420a
Compare
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 78 out of 82 changed files in this pull request and generated 8 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
kimorris27
force-pushed
the
kimorris27/ARO-23228-typespec-migration
branch
from
f827a6b to
edfc884
Compare
SudoBrendan
reviewed
Apr 30, 2026
…RO-HCP Modelling `api` directory structure after ARO-HCP's
- `api/package.json` came from ARO-HCP; I removed Autorest - Ran `npm install` on my Mac to initialize `api/package-lock.json` - Created `Dockerfile.typespec` by copying `Dockerfile.autorest` and tweaking Note that I considered combining the Autorest and TypeSpec stuff into a unified "api tooling" image, but I ended up in dependency hell trying to get the Autorest implementation of `make client` working and so decided to use separate images (we theoretically don't need Autorest anymore anyway)
…rate-swagger` as `make generate-swagger-legacy` We probably don't need the old one anymore, but preserving it on the off chance that we do; it doesn't hurt anything
…able API, the only one we're generating from TypeSpec so far Motivation to use `api` as the source of truth for the current API version and newer ones is that it makes it easier to commit to upstream since the directory structures match; I think this outweighs the minor confusion/inconvenience of having two sets of Swagger API specs in two different places Other note: the new `make` target generates the examples with `oav` (referenced in ARO-HCP docs and used for their examples), and the examples seem to have changed between Autorest and `oav`; so these new examples are technically different from what's currently present in azure-rest-api-specs for this API version, but I say we don't worry about this until/unless it becomes a problem
…pi` directory along with a few other tweaks... - `hack/swagger` -> `hack/swagger-legacy` - Got rid of `hack/apiclients` and gathered a few things all related to API/client tooling into `hack/api`
… the fact that TypeSpec complains about conflicts with examples if you don't delete them before generating the Swagger This means that anyone who runs `make generate` will have to understand not commit the changed examples; I know this is a little annoying, but I think it's important to include the TypeSpec -> Swagger generation in `make generate` and the corresponding CI check (`git add *` is not a great practice anyway IMO)
- Typo in TypeSpec Dockerfile entrypoint - A little bit of a hack to ensure `node_modules` is initialized properly for running npm scripts in the container rather than on the host - Encapsulate `oav generate-examples` in an npm script
…typespec` Didn't think about how CI would be affected by containerizing TypeSpec stuff Note that `tsp format` output changed between containerized and non-containerized version for now; just pushing this to see how the CI generate check reacts for now
… check for diffs to API We don't really need a "top-level" `make generate`. API changes are rare, so we don't need to check for changes every time we build the RP. But we do still want CI to make sure there are no unintended diffs. Note that HCP doesn't have a top-level generate target; they keep the API generation separate as well
Copilot commented about how these needed to be updated (`swagger` -> `swagger-legacy`) to account for my changes, and when I dug into it, I realized these weren't being used at all - `make generate-swagger-legacy` (which was `make generate-swagger` before my changes) invokes the swagger hack directly rather than doing so through `make generate`. `make generate` doesn't run these generate commands since `pkg/api` is its own module.
… Copilot's suggestion
…ec (seems to have been an upstream mistake
kimorris27
force-pushed
the
kimorris27/ARO-23228-typespec-migration
branch
from
3d9f2db to
8def41d
Compare
kimorris27
force-pushed
the
kimorris27/ARO-23228-typespec-migration
branch
from
8def41d to
4084e7d
Compare
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 92 out of 96 changed files in this pull request and generated 3 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Which issue this PR addresses:
First in a series of PRs for https://redhat.atlassian.net/browse/ARO-23228
What this PR does / why we need it:
This PR sets us up to generate the Swagger API specifications for the v20250725 API and any future API versions from TypeSpec rather than from the Go structs in
pkg/api. It also relocates the spec for the v20250725 API fromswaggertoapi.Many of the files changed in this PR are generated or copied from the upstream azure-rest-api-specs repo. You'll have the best review experience going through the commits, where I explain in detail what each one does.
Test plan for issue:
Had to run new make targets locally to generate Swagger and examples; also ran
make generate-swagger-legacyto make sure it still workedIs there any documentation that needs to be updated for this PR?
Doc changes are included in this PR
How do you know this will function as expected in production?
API spec for v20250725 has not functionally changed; it's just generated differently.
See Azure/azure-rest-api-specs#41462 if you're curious about any diffs between the pre-TypeSpec and post-TypeSpec versions of the v20250725 API spec.